1. Introduction

When an AI Agent possesses system-level capabilities such as shell execution, file read/write, network requests, and scheduled tasks, it is no longer just a “chatbot”—it is an operator with real permissions. This means: a single command triggered by prompt injection could delete critical data; a supply chain-poisoned Skill could quietly leak credentials; and an unverified business operation could cause irreversible loss.
Traditional security solutions usually lean toward two extremes: either relying entirely on the AI’s own “judgment” for self-restraint (which is easily bypassed by meticulously crafted prompts) or piling up rigid rules that lock the Agent down (stripping away the Agent’s core value).

This guide chooses a third path: dividing security responsibilities based on “who performs the check,” ensuring three distinct roles fulfil their respective duties:

General Users: Serving as the final line of defence, responsible for key decisions and periodic reviews. We provide best practices to reduce cognitive load.
The Agent Itself: Consciously adhering to behavioural norms and audit processes during runtime. We provide Skills to inject security knowledge directly into the Agent’s context.
Deterministic Scripts: Mechanically and faithfully executing checks, immune to prompt injection. We provide Scripts to cover common, known danger patterns.

No single checker is omnipotent. Scripts cannot understand semantics, Agents can be deceived, and humans experience fatigue. However, by combining all three, we can guarantee the convenience of daily use while simultaneously defending against high-risk operations.

2. General Users (Precautions)

Users are the ultimate line of defence and the holders of the highest authority in the security system. The following are security matters that users must personally attend to and execute.

a) API Key Management:

Set proper permissions for configuration files to prevent unauthorised access:

Never commit API keys to code repositories!

b) Channel Access Control (Critical!)
You must set a whitelist (allowFrom) for every communication channel; otherwise, anyone will be able to chat with your Agent:

⚠️ In the new version, an empty allowFrom means all access is denied. If you want to open it, you must explicitly write [“*”], but this is not recommended.

c) Do Not Run as Root
It is recommended to create a dedicated user to run the Agent to avoid excessive permissions:

d) Avoid Using Email Channels Where Possible

Email protocols are complex and carry relatively high risks. Our BitsLab team has discovered and confirmed a [Critical] level vulnerability related to email. Below is the project team’s response; we still have several issues awaiting their confirmation, so please exercise caution when using email-related functional modules.

e) Recommended Deployment in Docker
It is recommended to deploy Nanobot in a Docker container to isolate it from your daily operating environment, preventing security risks caused by mixed permissions or environments.

3. Tool Installation Steps

The following tools are part of the proprietary toolkit developed by BitsLab. For more details, visit the official repository: https://github.com/BitsLabSec/nanobot-security-guide

① Download the nanobot-security-guide project to your nanobot skills directory, or send a command to the Agent to run the official installation script:
curl -sSL https://raw.githubusercontent.com/BitsLabSec/nanobot-security-guide/main/install.sh | bash
↓
② Once installation is complete, read the security practice guides within the project (such as README.md and SKILL.md) to understand core security configurations and operational recommendations.
↓
③ Send a command to your Agent: “Please read this security guide carefully and evaluate whether it is reliable.”
↓
④ Following the document prompts, manually configure allowlist.txt and runtime-baseline.txt in the policy/ directory to tighten permissions and establish security baselines.
↓
⑤ Use the scripts in the scripts/ directory to perform security inspections and testing to ensure environmental safety.

4. Tool Principles

SKILL.md

Intent auditing based on “Cognitive Awakening” breaks through the blind spots where traditional AI passively receives instructions. It features a built-in, mandatory “Self-Wakeup” Chain of Thought (CoT) mechanism that requires the AI to awaken an independent security-auditor persona in the background before processing any user request. By performing contextual analysis and independent judgment of user intent, it actively identifies and intercepts potential high-risk threats, upgrading the system from “mechanical execution” to an “Intelligent Firewall.” When malicious commands (such as reverse shells, sensitive file theft, or large-scale deletions) are detected, the tool executes a standardised hard-interception protocol (outputting a warning: [Bitslab nanobot-sec skills detected sensitive operation…, Intercepted]).

Malicious Command Execution Interception (Shell & Cron Protection)

Acts as a “Zero Trust” gateway when the Agent interacts with OS-level commands. This line of defence directly blocks various destructive operations and dangerous payloads (such as rm -rf malicious deletions, permission tampering, reverse shells, etc.). Simultaneously, the tool provides deep runtime inspection capabilities, actively scanning and cleaning system processes and cron jobs for persistent backdoors and malicious execution signatures, ensuring the absolute safety of the local environment.

Sensitive Data Theft Prevention (File Access Validation)

Implements strict physical read/write isolation for core assets. The system presets rigorous file validation rules, strictly forbidding the AI from unauthorised reading and exfiltration of sensitive files containing API keys and core configurations, such as config.json or .env. Furthermore, the security engine performs real-time auditing of file-reading logs (e.g., the invocation sequence of the read_file tool) to completely sever the possibility of credential leakage or data exfiltration at the source.

MCP Skill Security Auditing

For the MCP (Model Context Protocol) class, the tool automatically audits contextual interactions and data-processing logic. It detects risks such as sensitive information leakage, unauthorised access, and dangerous command injections, and cross-references them against security baselines and whitelists.

New Skill Downloads and Automated Security Scanning

When downloading new skills, the tool uses auditing scripts to perform automated static analysis of the code, compare it against security baselines and whitelists, and detect sensitive information or dangerous commands. This ensures that skills are safe and compliant before they are loaded.

Anti-Tamper Hash Baseline Verification

To ensure absolute Zero Trust of underlying system assets, the protection shield continuously establishes and maintains SHA256-encrypted signature baselines for critical configuration files and memory nodes. The nightly inspection engine automatically verifies chronological changes in file hashes, capturing any unauthorised tampering or malicious overwrites within milliseconds. This completely eliminates the risk of local backdoor implantation or “poisoning” at the physical storage layer.

Automated Disaster Recovery Backup and Snapshot Rotation.

Given that local Agents possess high-level read/write permissions for the file system, the system includes a top-tier automated disaster recovery mechanism. The protection engine automatically triggers a full sandbox-level archive of active workspaces every night, maintaining a security snapshot mechanism with a 7-day retention policy (auto-rotation). Even in extreme cases of accidental damage or erroneous deletion, the development environment can be rolled back losslessly with one click, maximising the continuity and resilience of local digital assets.

5. Disclaimer
   This guide is intended solely as a reference for security practices and does not constitute any form of security guarantee.

No Absolute Security: All measures described in this guide (including deterministic scripts, Agent Skills, and user precautions) are “best-effort” protections and cannot cover all attack vectors. AI Agent security is a rapidly evolving field, and new attack methods may emerge at any time.

User Responsibility: Users deploying and using Nanobot should independently assess the security risks of their operating environment and adjust the recommendations in this guide according to their specific scenarios. Any losses resulting from incorrect configuration, failure to update promptly, or ignoring security warnings are the sole responsibility of the user.

Not a Substitute for Professional Security Audits: This guide is not a replacement for professional security audits, penetration testing, or compliance assessments. For scenarios involving sensitive data, financial assets, or critical infrastructure, it is strongly recommended to hire a professional security team for an independent evaluation.

Third-Party Dependencies: The security of third-party libraries, API services, and platforms that Nanobot relies on (such as Telegram, WhatsApp, and LLM providers) is beyond the scope of this guide. Users should monitor security advisories for relevant dependencies and update them promptly.

Scope of Non-Liability: The maintainers and contributors of the Nanobot project shall not be held liable for any direct, indirect, incidental, or consequential damages arising from the use of this guide or the Nanobot software.

Use of this software indicates that you understand and accept the aforementioned risks.